Xlet Resource Budgets

The resource constraints of an Xlet can be defined in the xlet.properties file, or by including a file xlet.budgets into the Xlet’s jar file before the file is signed. Properties in xlet.properties take precedence over properties in xlet.budgets. The budgets file has the format of a Java properties file specified in the Java API.

Example:

xlet.maxNumberOfThreads=30
xlet.timeBudget=9s/10s
xlet.priorityIfTimeBudgedExceeded=0
xlet.period=1s
xlet.timeBudget.paused=300ms
xlet.timeBudget.running=800ms

Properties:

Number of Threads
Time Budgets

Number of Threads

xlet.maxNumberOfThreads = <n>
If <n> is larger than 0 the number of active threads will be limited by this number.

A value of 0 is not permitted and will cause an error when starting the Xlet.

If an Xlet attempts to exceed the number of threads permitted for it, calls to Thread.start() will result in an exception, e.g.,

java.lang.Error: ThreadGroup is limited to 10 threads, contains 10, so add is not allowed.

 

An Xlet may create an arbitrary number of instances of class java.lang.Thread, and there is no limit on the number of calls to start() on these threads. However, the number of threads that may be alive simultaneously is limited by this property. To be sure that a thread is no longer alive, a call to Thread.join() is required. Before a call to Thread.join(), the thread may have finished its Java execution, but it may still not have been released back to the AMS’s thread pool.

Note that the number or threads specified here includes all threads that are created internally by the AMS, LWUIT graphics, standard libraries, etc. An Xlet has at least two internal threads, one for starting, pausing, and stopping the xlet, and one of LWUIT graphics. So, to allow the creation of one additional thread by the Xlet, this budget has to be set to 3 or higher.

Determining Number of Xlet Threads for your app

Xlet developers should be aware of the following thread allocations performed by the Kona library.

Sensor - 6 (i.e. 1 + 5 different PPS Objects)

One thread is used by the Implementation and there are 5 additional threads which are for 5 different PPS objects. These threads are only created if the application opens a SensorConnection to any of the sensor which belong to a particular PPS object. The list of sensors which belong to the 5 different PPS object are listed below :
  1. PollingDurationOne, PollingDurationTwo, ..., PollingDurationSeven and PollingIntervalOne, PollingIntervalTwo, PollingIntervalThree, ...., PollingIntervalSeven are all using one thread as all belong to one PPS Object.
  2. StartTime1,StartTime12 ... StartTime7 are all using one thread as all belong to one PPS Object.
  3. WakeupReason is in a seperate PPS object hence a seperate thread will be created if a SensorConnection is opened for the same.
  4. UConnectData is written to a seperate PPS object hence a seperate thread will be created if a SensorConnection is opened for the same.
  5. Remaining all the sensors are in a single PPS object hence if a SensorConnection is established for any of the sensors apart from the above listed sensors , one thread will be created.

    Hence even if we say that the Sensors API uses 6 threads, but if an application uses the sensors to any one of the 5 groups listed above, in that case only 2 threads will be created by the sensors implementation.

    WMA - 1

    RMS - 1

    OpenNav - 1

    VR – 1

    Location - 2

    IXC also generates a thread to service every remote request that is created. So if your Xlet generates 3 simultaneous requests, 3 threads will be generated. Once each request is complete, the thread is destroyed.

    DeviceInputImpl, will genereate a thread to help manager scroll knob events. The thread is created to buffer the amount of events received and then destroyed after all of the events have been dispatched.

    Top

    Time Budgets

    The following properties specify per-Xlets CPU time budgets.
    • xlet.period (the period after which CPU budgets get replenished)
    • xlet.timeBudget.paused (CPU budget for state Paused,default: same as period)
    • xlet.timeBudget.running (CPU budget for state Running, default: same as period)

    CPU budgets for an Xlet are enabled, if the property xlet.period is defined. If xlet.timeBudget.paused or xlet.timeBudget.running is defined, then xlet.period must also be defined.

    xlet.timeBudget = [m]s/[m]s \ {, [m]s/[m]s } (Required)

    Via the property xlet.timeBudget, the CPU time budget of an Xlet can be specified.

    The time budget is specified as a budget of CPU time that is permitted over a given interval of time. Both, budget and interval can be specified in seconds (s) or microseconds (ms). To permit an Xlet to use 50% of the CPU time over a 10 seconds interval, you can specify 5s/10s. It is possible to specify several budgets and corresponding intervals, such that, e.g., short term CPU usage peaks can be permitted while longer term usage can be restricted.

    For example, specifying 900ms/1s,10s/100s would permit 90% CPU usage during any second, but will limit the long term CPU usage to 10% over a 100 seconds interval.

    In order to establish a counter-measure against an Xlet that exceeds a defined time budget, xlet.priorityIfTimeBudgetExceeded must be defined.

    xlet.priorityIfTimeBudgetExceeded = 0 (Required)

    xlet.period = <n> (Required)

    The period at which the AMS will reset the time slice accumulation to zero and return the app threds to normal priority.

    Start with 1 second.

    xlet.timeBudget.paused = <n> (Required)

    The limit of accumulated time slices at which the AMS will reduce the priority of xlet threads while in the xlet paused state.

    Start with 300ms.

    xlet.timeBudget.running = <n> (Required)

    The limit of accumulated time slices at which the AMS will reduce the priority of xlet threads while in the xlet Running state.

    Start with 800ms.

    Top